---
title: useFocusTrap
description: The useFocusTrap hook provides accessibility-focused keyboard navigation management, keeping focus trapped within modal components for better user experience.
lastModified: 2025-08-28
---

The `useFocusTrap` hook creates an accessible experience by preventing keyboard focus from leaving a specific container element (like a dialog or modal) until it's dismissed. This is essential for users navigating with keyboards or screen readers.

## Usage

```tsx
import { useRef } from 'react';
import { useFocusTrap } from '@c15t/react';

const CustomCard = ({ children, ref, ...props }) => {
  const localRef = useRef(null);
  const cardRef = ref || localRef;
  
  useFocusTrap(true, cardRef);
  
  return (
    <div
      ref={cardRef}
      tabIndex={0}
      aria-modal={true}
      role="dialog"
      {...props}
    >
      {children}
    </div>
  );
};
```

## How It Works

When activated, the `useFocusTrap` hook:

1. Stores the element that was focused before trapping began
2. Finds all focusable elements within the container
3. Sets initial focus to the first focusable element (or the container itself)
4. Captures Tab and Shift+Tab keystrokes to cycle focus within the container
5. Restores focus to the original element when the component unmounts or `shouldTrap` becomes false

## Notes

- Hook must be called with a valid element reference that contains focusable elements
- Adding `tabIndex={0}` to the container ensures it can receive focus if no focusable children exist
- Always include proper ARIA attributes (`role="dialog"` and `aria-modal="true"`) for screen reader accessibility
- The hook automatically restores focus to the previously focused element when the component unmounts
- Set `shouldTrap` to false when you want to disable focus trapping temporarily

## Accessibility Compliance

Using this hook helps your application comply with these WCAG 2.1 requirements:

- [2.1.2: No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap.html) - While this criterion warns against trapping keyboard focus, modal dialogs are an exception when implemented properly
- [2.4.3: Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html) - Ensures focus moves in a meaningful sequence
